Prevent S6 startup races: services wait for their config oneshots and depend on base - #689

Why we created this PR

When a container built from our S6 images runs as root (for example, following the advice in #425), php-fpm sometimes fails on its first start:

ALERT: [pool www] user has not been defined
ERROR: failed to post process the configuration
ERROR: FPM initialization failed

S6 restarts it and the container recovers, so it looks like noise. It's a race. PHP-FPM refuses to start as root without a user in the pool config. Our 5-fpm-pool-user oneshot writes that line, but php-fpm never declared that it depends on the oneshot, so S6 started both at once. On the same boot, nginx and apache2 could also start before 10-init-webserver-config rendered their config.

Rootless containers never hit it because PHP-FPM ignores the user directive when it isn't root. On main, the error reproduces on every root-mode boot.

While fixing the dependency, we found two more things that S6 Overlay documents and we weren't doing:

1. We used the deprecated flat dependencies file. The s6-overlay README only documents dependencies.d/ directories, and s6-rc marks the flat file deprecated. With the directory format, a dependency is one empty file, so the whole fix is a touch.
2. None of our services depended on base. The README is direct about it: services that don't depend on base "might have been started earlier, which may cause race conditions - so it's recommended to always make them depend on base."

How to test

serversideup/php-dev:689-*

View the testing images →

To see the race yourself, build this against serversideup/php:8.4-fpm-nginx-alpine (fails) and against a 689- image (passes):

FROM serversideup/php:8.4-fpm-nginx-alpine
USER root
RUN docker-php-serversideup-s6-init

cid=$(docker run -d --rm my-test-image); sleep 6
docker logs $cid 2>&1 | grep -c 'user has not been defined'   # 1 before, 0 after
docker stop $cid

What this PR does

Startup order

• php-fpm now waits for 5-fpm-pool-user; nginx and apache2 wait for 10-init-webserver-config and php-fpm
• Every service and every generated oneshot now depends on base, as S6 Overlay recommends

Before (main): php-fpm, nginx, and apache2 start the moment S6 is up, in parallel with the oneshots that write their config.

flowchart LR
    subgraph oneshots [Entrypoint oneshots]
        a[0-container-info] --> b[1-log-output-level]
        b --> c[5-fpm-pool-user]
        b --> d[10-init-webserver-config]
        d --> e[50-laravel-automations]
    end
    subgraph services [Long-running services]
        fpm[php-fpm] --> web[nginx / apache2]
    end
    c -. race .- fpm
    d -. race .- web

After: every service and oneshot depends on base, and each service waits for the oneshot that configures it.

flowchart LR
    base --> a[0-container-info] --> b[1-log-output-level]
    b --> c[5-fpm-pool-user] --> fpm[php-fpm]
    b --> d[10-init-webserver-config] --> e[50-laravel-automations]
    d --> web[nginx / apache2]
    fpm --> web

Every node above also lists base directly in its dependencies.d/; those edges are omitted to keep the diagram readable.

S6 Overlay alignment

• Replaced the flat dependencies files for php-fpm, nginx, and apache2 with dependencies.d/ directories
• docker-php-serversideup-s6-init now has one add_dependency helper (a mkdir -p and a touch) used for oneshot chaining and for the service dependencies above

Docs

• Added dependencies.d and base guidance to Adding your own start-up scripts

Compatibility

Stock images and rootless containers behave the same. If you appended lines to our old flat dependencies files in your own Dockerfile, S6 now ignores those files once dependencies.d/ exists. Move each line to an empty file in dependencies.d/ instead.

add_startup_dependency php-fpm 5-fpm-pool-user
add_startup_dependency nginx 10-init-webserver-config
add_startup_dependency apache2 10-init-webserver-config